|
|
PATH Hardware Documentation
> USB Devices
> Mac OS USB DDK API Reference
|
A pipe's state is governed by two factors:
The USL state can be one of the following:
A transaction error (errors -6915 to -6901) causes the pipe to enter the stalled state. The class driver can change the state of the pipe using the functions in this section.
Note that the pipe and interface control functions differ from most other USL calls in these two ways:
Also note that pipe 0 to a device cannot be stalled. If a communication error happens on pipe 0, the stall is automatically cleared before the call completes. Thus some of these functions can affect a device's default pipe 0 and some can't. Those functions that operate on both the default pipe 0 and pipes other than pipe 0, take a device reference for the default pipe or a pipe reference for a specific pipe. Those functions that can't affect the default pipe, take only a pipe reference.
These calls can be used on a device's default pipe 0:
USBGetPipeStatusByReference
USBAbortPipeByReference
USBResetPipeByReference
These calls cannot be used on a device's default pipe 0:
USBClearPipeStallByReference
USBSetPipeIdleByReference
Except for entering the stalled state on an error, the USL does not keep track of the state of the device's endpoint. The class driver must keep track of the state of the endpoint.
When a pipe is reset, aborted, or had a stall cleared, the expected data toggle on that pipe's endpoint is reset to data0. This means that the next packet read on that pipe may be discarded unless the device is told to synchronize its endpoint data toggle.
The method of synchronizing the endpoint for the device is device specific. In general, it should be possible to perform endpoint data toggle synchronization with a call to the USBDeviceRequest function addressed to the endpoint in question. A USB device request command of CLEAR_FEATURE and a feature selector of ENDPOINT_STALL should complete the required data toggle synchronization.
The USBGetPipeStatusByReference function returns status on a specified pipe or the device's default pipe 0.
OSStatus USBGetPipeStatusByReference(USBReference ref,
USBPipeState *state);
Errors returned by the USBGetPipeStatusByReference function include:
kUSBUnknownPipeErr
|
-6997 | pipe reference specified is unknown |
In version 1.0 of the USB Services software the USBGetPipeStatusByReference function does not operate as defined above. If the pipe is not active, it returns an error and the state is not set. The USBGetPipeStatusByReference function does work as defined in version 1.0.1 and later of the USB Services software. If noErr is returned, the state is returned correctly. If this call returns an error, the error should be examined to see what state the pipe is in.
Errors returned by the USBGetPipeStateByReference function include:
noErr
|
0 | specified pipe is active |
kUSBPipeIdleErr
|
-6980 | specified pipe is in the idle state |
kUSBPipeStalledErr
|
-6979 | specified pipe is stalled |
The USBAbortPipeByReference function aborts operations on a specified pipe or the device's default pipe 0.
OSStatus USBAbortPipeByReference(USBReference ref);
All outstanding transactions on the pipe are returned with a kUSBAborted status. The state of the pipe is not affected.
After this function is called, the device's endpoint needs to be synchronized with the host's endpoint. See Data Toggle Synchronization for information about how to accomplish endpoint data toggle synchronization.
Errors returned by the USBAbortPipeByReference function include:
kUSBUnknownPipeErr
|
-6997 | pipe reference specified is unknown |
The USBResetPipeByReference function resets the specified pipe or the device's default pipe 0.
OSStatus USBResetPipeByReference(USBReference ref);
All outstanding transactions on the pipe are returned with a kUSBAborted status. The pipe status is set to active. The stalled and idle state are cleared.
After this function is called, the device's endpoint needs to be synchronized with the host's endpoint. See Data Toggle Synchronization for information about how to accomplish endpoint data toggle synchronization.
IMPORTANT
For USB parameter block version 1.0, the implementation of USBResetPipeByReference does nothing if passed a real pipe reference. However, if the function is passed a non-existant pipe reference, it will corrupt low memory. Version 1.0.1 and later of the USB Services software corrects this problem.
Errors returned by the USBRestPipeByReference function include:
kUSBUnknownPipeErr
|
-6997 | pipe reference specified is unknown |
In version 1.0 of the USB Services software, the pipe may or may not have been made active, depending on whether the pipe was previously stalled or not, and the kUSBPipeIdleErr is returned. If an idle pipe was not stalled, it is not affected. If an idle pipe was stalled, it is made active. In version 1.0.1 and later of the USB Services software this behavior is corrected.
In version 1.0 of the USB Services software, the kUSBPipeStalledErr is returned if the pipe was previously idle and the call succeeded despite the error. This behavior is not an error and noErr is returned in verions 1.0.1 and later of the USB Services software.
kUSBPipeStalledErr
|
-6979 | pipe stalled, pipe is reset despite the error |
The USBClearPipeStallByReference function clears a stall on the specified pipe. This call can only be used on a pipe, not on a device's default pipe 0.
OSStatus USBClearPipeStallByReference(USBPipeRef ref);
All outstanding transactions on the pipe are returned with a kUSBAborted status. The pipe status is set to active; if the pipe was previously idle it is set back to idle. The stalled state is cleared, idle is not.
A call to this function does not clear a device's endpoint stall. The class driver has to take care of that by using USB standard device commands, such as CLEAR_ENDPOINT_STALL . The class driver may need to take other remedial actions.
After this function is called, the device's endpoint needs to be synchronized with the host's endpoint. See Data Toggle Synchronization for information about how to accomplish endpoint data toggle synchronization.
Errors returned by the USBClearPipeStallByReference function include:
kUSBUnknownPipeErr
|
-6997 | pipe reference specified is unknown |
kUSBPipeIdleErr
|
-6980 | specified pipe is in the idle state |
The USBSetPipeIdleByReference function sets a specified pipe to the idle state. This call can be used only on a specified pipe, not on a device's default pipe 0.
OSStatus USBSetPipeIdleByReference(USBPipeRef ref);
The state of the pipe is set to idle. No outstanding transactions are affected.
Errors returned by the USBSetPipeIdleByReference function include:
kUSBUnknownPipeErr
|
-6997 | pipe reference specified is unknown |
In version 1.0 of the USB Services software, the following errors are returned if the pipe is not currently active. In these instances, the call has succeeded despite the returned error. This behavior is not an error and noErr is returned in verions 1.0.1 and later of the USB Services software.
kUSBPipeIdleStalled
|
-6979 | pipe was stalled, pipe is still active despite error |
kUSBPipeIdleErr
|
-6980 | specified pipe is in the idle state |
The USBSetPipeActiveByReference function sets the state of a specified pipe to active.
OSStatus USBSetPipeActiveByReference(USBPipeRef ref);
The pipe status is set to active if the pipe is not stalled. The idle state is cleared, stalled is not.
Errors returned by the USBSetPipeActiveByReference function include:
kUSBUnknownPipeErr
|
-6997 | pipe reference specified is unknown |
kUSBPipeIdleStalled
|
-6979 | pipe was stalled, pipe is set idle |
In version 1.0 of the USB Services software, the following error is returned if the pipe was previously idle. In this instance the call has succeeded despite the returned error. This behavior is not an error and noErr is returned in verions 1.0.1 and later of the USB Services software.
kUSBPipeIdleErr
|
-6980 | pipe was previously idle, pipe is still made active |
Previous | Back Up One Level | Next |